{
    title:  "ESP Overview",
    crumbs: []
}

            <h1>Embedthis ESP&trade;</h1>
            <div class="floated">
                <img src="images/esp-icon-128.png" class="ui left floated image" alt="esp">
                <p>ESP is a web framework that makes it dramatically easier to create blazing fast,
                dynamic web applications and web sites. ESP applications uses the <em>C</em> language for server-side 
                programming, which allows easy access to system or hardware data. The result is fast and 
                responsive web applications.</p>

                <p>ESP is not a traditional low-level environment. It is a powerhouse MVC framework in a tiny footprint.
                ESP has all the features you would normally expect from an enterprise web framework. ESP is also 
                great for development. If web pages or controllers are modified, the code is transparently 
                recompiled and reloaded. This enables unparalleled performance with "script-like" flexibility for 
                web applications. </p>
            </div>
            
            <h2>ESP Components</h2>
            <p>The ESP web framework provides a complete set of components including</p>
            <ul>
                <li>HTTP web server</li>
                <li>Model-View-Controller framework</li>
                <li>Dynamic loader for <em>C</em> controllers</li>
                <li>Templating with embedded <em>C</em> code in web pages</li>
                <li>Application and scaffold generator</li> 
                <li>Web Sockets</li>
                <li>Embedded databases</li>
                <li>Database migrations</li>
                <li>Extensive programmer API</li>
                <li>Library of extension packages</li>
                <li>Complete tooling for deploying web applications</li>
            </ul>
            <p>This document describes the ESP web framework and how to use ESP.</p>
            
            <a id="patterns"></a>
            <h2>ESP Patterns</h2>
            <p>ESP supports several design patterns:</p>
            <ul>
                <li>Stand-alone ESP web pages</li>
                <li>Web Services via ESP Controllers</li>
                <li>ESP Model-View-Controller applications 
                    (<a href="http://en.wikipedia.org/wiki/Model-view-controller">MVC</a>)</li>
                <li>Single Page Applications 
                    (<a href="http://en.wikipedia.org/wiki/Single-page_application">SPA</a>)</li>
            </ul>

            <p>Your applications can choose a predominating pattern or you can mix patterns in a 
                single application if desired.</p>
            <a name="standalone"></a>
            <h2>Stand-alone Pages</h2>
            <p>An ESP page is a standard HTML web page with embedded <em>C</em> code that executes at run-time to create a dynamic
            client response. Pages typically have a "<em>.esp</em>" extension and may use ESP layout pages to
            define the look and feel of the application in one place.</p>
            <p>The C code is embedded between <em>&lt;%</em> and <em>%&gt;</em> tags. For example:
<pre class="code">&lt;h1&gt;Hello World&lt;/h1&gt;
&lt;p&gt;<b>&lt;% render("A random number %d", rand(0)); %&gt;</b>&lt;/p&gt;</pre>
            <p>When the web page is requested, the web page including the code inside the ESP tags is compiled
            and saved as a shared library. When the page is requested, the call to <em>render</em> will 
            replace the code between <em>&lt;% ... %&gt;</em> with the result of the render call. Finally,
            then the composite page will be sent to the client. The next time the page is requested, it will 
            be transparently recompiled and reloaded if the source web page has been modified
            See <a href="#pages">ESP Pages</a> below for more details.</p>

            <a name="webservices"></a>
            <h2>Web Services</h2>
            <p>ESP is especially well suited for high performance web services. ESP permits the binding of URLs 
            directly to <em>C</em> functions. When the URL is requested, the corresponding <em>C</em> function, typically
            called an <em>action</em>, is executed to dynamically generate a response. 
            The actions are typically grouped into a loadable ESP controller file. For example:</p>
            <pre class="code">
/* Hello Action */
static void <b>hello()</b> { 
    render("{greeting: 'Hello World'}\n");
    finalize();
}

/* Initialization of Actions */
ESP_EXPORT int esp_module_greeting(HttpRoute *route) {
    espDefineAction(route, "greeting-hello", <b>hello</b>);
    return 0;
} 
</pre>
            <p>This example is a loadable ESP controller with one action function. The actions are published by 
            binding functions to route names. When the appropriate URL is requested, the <em>hello</em> function 
            is run to generate the response. During development, if the file containing this code is modified, 
            the page will be transparently recompiled and reloaded before running the new code.</p>

            <a name="mvc"></a>
            <h2>Model-View-Controller</h2>
            <p>A Model-View Controller application, also known as an MVC app, is a proven paradigm for organizing larger web
            applications. In this pattern, it is the "model" that manages the state of the application including the 
            database. The "controller" responds to inputs and invokes then the relevant "views" to generate the 
            user interface. Originally developed in the '70s, it has been more recently adapted for web applications and been
            popularized by frameworks such as <a href="http://www.rubyonrails.org">Ruby on Rails</a>. ESP uses the
            same paradigm with an embedded spin.</p>
            <p>ESP supports MVC applications and provides an <em>esp</em> application generator to create MVC 
            applications and scaffolds. ESP support two styles of MVC applications:</p>
            <ul>
                <li>Server-side MVC Applications</li>
                <li>Single Page Applications</li>
            </ul>

            <h3>Server-side MVC Applications</h3>
            <p>ESP implements server-side MVC applications by providing using the 
            <a href="https://embedthis.com/expansive/">Expansive</a> web site generator. Expansive provides
            development time scripting, layout pages, partial pages to support the easy insertion of dynamic 
            data into web pages before they are delivered to the client. A common look-and-feel is achieved 
            by using master layout pages.</p>

            <a name="spa"></a>
            <h3>Single Page Applications</h3>
            <p>Single page applications deliver the entire web application as a single page and then incrementally
            download resources and data in the background as required. With this paradigm, it is the client that 
            defines the entire user interface via a client-side Javascript framework such as 
            <a href="http://aurelia.io">Aurelia</a>. The server provides the initial page load and ongoing data. 
            This approach can provide a more responsive and fluid user experience without the delays caused by 
            page reloads. ESP is well suited to SPA applications and can deliver all the required resources and 
            data for such apps.</p>

            <h2>ESP Web Framework</h2>
            <img src="images/espArchitecture.jpg" alt="ESP Web Framework Architecture" class="centered" />
            <p>The main components of the ESP Web Framework are:</p>
            <ul>
                <li><a href="#http">HTTP Web Server</a></li>
                <li><a href="#pages">ESP Pages</a></li>
                <li><a href="#controllers">ESP Controllers</a></li>
                <li><a href="#models">ESP Models</a></li>
                <li>ESP Compilation</li>
                <li>ESP Generator</li>
                <li><a href="#api">ESP API</a></li>
            </ul> 
            
            <a id="http"></a>
            <h2>HTTP Web Server</h2>
            <p>ESP includes the 
                <a href="https://embedthis.com/appweb/">Embedthis HTTP engine</a> that has been used for years
                in <a href="https://embedthis.com/appweb/">Appweb</a>. This is a high performance,
               event-based, multithreaded HTTP engine. It fully supports HTTP/1.1 with extensions for WebSockets,
               Sessions, SSL, Security Limits and Defensive counter-measures.</p>

            <a id="pages"></a>
            <h2>ESP Pages</h2>
            <p>ESP Pages provide the "View" portion of MVC frameworks and are responsible for generating 
            the user interface. They provide: </p>
            <ul>
                <li>Embedded <em>C</em> language code for dynamic HTML responses</li>
                <li>An ESP API library of convenience routines to manage web requests, session state and render output</li>
            </ul>
            <p>Note that if using ESP for a <a href="#spa">Single Page Architecture</a> application, the views are
            typically generated by the client using a client-side framework such as 
            <a href="http://aurelia.io">Aurelia</a>. In this case, ESP views are used for the initial, single home page.</p>

            <h3>ESP Page Directives</h3>
            <p>ESP supports the following special sequences for use in web pages.</p>
            <table class="ui table" title="directives">
                <thead><tr><th class="three wide">Directive</th><th>Purpose</th></tr></thead>
                <tbody>
                    <tr><td class="">&lt;% code %&gt;</td><td>Insert code at this location. At run-time, this 
                        <em>C</em> code will execute.</td></tr>
                    <tr><td>&lt;%= code %&gt;</td><td>Evaluate the expression and substitute the resulting value 
                        into the web page at this position. A printf format specifier can be used to specify a 
                        different variable type. For example, <em>&lt;%= %d ivar %&gt;</em>
                        <em>C</em> code will execute.</td></tr>
                    <tr><td>%!variable</td><td>Shortcut for &lt;%= variable %&gt;</td></tr>
                    <tr><td>%!{expression}</td><td>Shortcut for &lt;%= expression %&gt;</td></tr>
                    <tr><td>%$param</td><td>Substitutes the value of a request parameter or session 
                        variable of the same name after HTML escaping the value.</td></tr>
                    <tr><td>%#field</td><td>Substitute the field name in the current database record.</td></tr>
                    <tr><td>%&#126;</td><td>Insert a URL to the top of the application.</td></tr>
                </tbody>
            </table>

            <p>See <a href="users/pages.html#directives">ESP Page Directives</a> for more details.</p>

            <a id="controllers"></a>
            <h2>ESP Controllers</h2>
            <p>ESP Controllers are collections of <em>C</em> functions that are bound to specific URLs for the purpose
            of managing a resource or group of resources. Often a controller will use 
            <a href="http://en.wikipedia.org/wiki/Representational_state_transfer">RESTful</a> routes to map 
            URLs to specific actions.</p>

            <p>A controller is typically coded in a single source file, though it can reference any external libraries.
            The controller will be dynamically compiled, saved and loaded when a request is received for any action 
            in the controller. If the source code is modified, the controller will be recompiled and reloaded. 
            Alternatively, the <em>esp</em> command can be used to precompile controllers so that a compiler 
            is not required on the target system in production. Compiled controllers are saved in a 
            <em>cache</em> directory as shared libraries.</p>
            
            <a id="actions"></a>
            <h3>Actions</h3>
            <p>When ESP receives a request to service, the request is parsed and then dispatched to a specific 
            function in the controller called an <em>action</em>. The job of the action function is to:</p>
            <ol>
                <li>Respond to the request</li>
                <li>Render a response view back to the client</li>
            </ol>
            <p>How the action responds to the request depends on the request parameters, the 
            query information, form parameters and other HTTP and application state information.</p>
            <p>Here is a sample action function that updates a database table based on user submitted form data in
            <em>"params"</em>.</p>
            <pre class="code">
static void update() {
    if (updateFields("post", params())) {
        inform("Post updated successfully.");
        redirect("list");
    } else {
        renderView("post-edit");
    }
}
</pre>
            <p>An action function can explicitly render data by calling one of the 
            <a href="ref/api/esp.html#group___esp_abbrev_1gaf89154adc3cbf6d6a6a32c6b4457c593">render</a> 
            methods.  It can redirect the client to a new URI via the 
            <a href="ref/api/esp.html#group___esp_abbrev_1ga79cf206805a9595395af14e7c35f289d">redirect</a> 
            method.</p> 
            
            <p>If the action method does not explicitly render any data, ESP will render an ESP web page of the same name 
            as the action function. That web page has full access to the controller and request state. This is a common
            pattern where a controller will respond to a request and an ESP view page will format the response to the 
            client.</p>

            <a id="models"></a>
            <h2>ESP Models and Databases</h2>
            <p>The Model part of an MVC framework stores the application data and access logic and may provide an 
            Object Relational Mapping (ORM) layer. Unfortunately, while being powerful and extensive, ORMs often 
            consume considerable amounts of memory and can be slow at run-time. ESP avoids this problem by providing 
            a simple mapping from relational database data to <em>C</em> based records and grids. This results in a 
            high-performance database interface with very low memory requirements.</p>
            <h3>Embedded Database Interface</h3>
            <p>ESP supports an Embedded Database Interface (EDI) above a user-selectable database such as:
            SQLite or MDB. The MDB database is a tiny, in-memory database &mdash; great for embedded applications.
            SQLite is a full SQL implementation for embedded applications. 
            MDB is the smallest and fastest, but has the least features.</p>
            <h3>Migrations</h3>
            <p>The ESP generator program can create database migration modules. These are mini-programs that create and
            modify database tables. Migrations are useful to create databases and test data.</p>

            <a id="api"></a>
            <h2>ESP API</h2>
            <p>The ESP web framework has an extensive suite of APIs to cover all possible design needs. It also
            defines an expressive, terse, short-form API that makes common tasks simple. 
            See the <a href="ref/api/esp.html">ESP API Reference</a> for more details.</p>
            <p>ESP uses a garbage collector so that you never need to free ESP memory allocated in web pages or
            in controllers. This results in more secure, reliable web applications.</p>
